EtherealMidi User's Guide
=========================

Contents
========

   1. What Is MIDI ?
   2. What Is EtherealMidi ?
      2.1 Origin
      2.2 Purpose
      2.3 Capability
   3. How Do I Use It ?
      3.1 Desktop
      3.2 Command Line
      3.3 SWI Interface
   4. Terms and Conditions
   5. Troubleshooting
   6. Known Bugs
      6.1 Acorn Compatible ?
      6.2 System Exclusive
   7. Acknowledgements
   8. Contact Address


1. What Is MIDI ?
=================

   This section is a layman's introduction to MIDI.
   
   MIDI stands for Musical Instrument Digital Interface. The system
   allows electronic instruments to communicate with each other using
   a standard 'language' - MIDI. It is not within the scope of this
   text to fully describe the MIDI language, but a basic description
   may remove a common misconception.

   MIDI is a type of serial interface. It transmits bytes
   one-bit-at-a-time, in a similar way to a modem. The language
   consists of byte (8-bit) messages which are normally between one
   and three bytes long. These messages are used to sequence MIDI
   events - turn notes on or off, change voice, add special effects,
   etc. They do *not* include the actual sound samples' data, in the
   way that SoundTracker files do. Hence, the music only sounds as
   good as your MIDI instrument.

   For a comprehensive introduction to MIDI, I suggest the following book :

   Practical MIDI Handbook by R A Penfold
   PC Publishing
   ISBN 1-870775-13-9

   '32 bit computers and software to match them are a bit thin on
    the ground at present [1990], but one of the standard add-ons
    for the powerful Acorn Archimedes RISC machines is a MIDI
    interface, and this could be the basis of the ultimate MIDI
    system.' (R A Penfold)


2. What Is EtherealMidi ?
=========================

   EtherealMidi is a FreeWare relocatable module that plays
standard MIDI format files as a background task.

2.1 Origin
----------
   This module was conceived because there was no freely available
   player for the Arc for (freely available) standard MIDI files. A
   C code player, midiplay v0.5 17-Nov-91, has been ported to the
   Arc. It has *no* connection with this software. It works
   reasonably as a foreground task, but is not a module and isn't
   fast enough to handle some pieces accurately. Due to these
   shortcomings, the EtherealMidi module concept grew into its
   present form.

2.2 Purpose
-----------
   The EtherealMidi module has been designed to administer a fast
   background task, suited to unobtrusive support of MIDI
   capability in the desktop and games environments.

2.3 Capability
--------------
   EtherealMidi currently (v4.07) supports :
    * Format 0 and 1 standard MIDI files.
    * One-shot or (delayed-) looping playback.
    * Simple CLI with on-line help.
    * Sophisticated SWI interface.
    * Intelligent double buffering.
    * Tailoring to individuals' MIDI systems.
    * System exclusive messages (including multi-part) - see note below.
    * Dynamic area memory, if available.
    * PollWord (RISC OS 3).
    * Pause.
    * MIDI file duration calculation.
    * Standard MIDI File format checking and diagnosis.

   Note: Though EtherealMidi supports System Exclusive messages,
         some MIDI modules (notably Acorn's own) fail to transmit
         them (see 'Known Bugs - System Exclusive').


3. How Do I Use It ?
====================

   This section gives a basic guide to using the CLI and SWI
   interface options. A full description is contained in the
   EtherealMidi Reference Manual.

3.1 Desktop
-----------
   For simple desktop use, run !Monolith and then double-click on
   valid MIDI files (filetype FD4).

   Alternatively, MIDI files can be dragged and dropped into the
   !Monolith icon, on the icon bar, or any !Monolith window.

3.2 Command Line
----------------
   From the command line, MIDI files can be played once through or looped by using :
      *EtherealPlay <filename>
      *EtherealLoop <filename>

   Omitting the filename in either case causes play to cease immediately.

   MIDI channels can be remapped using the *EtherealMap command.
   Users must understand the concept of MIDI 'channels' and know
   their own instrument's reception channels to use this command
   successfully. *EtherealMap will not be necessary if full
   16-channel reception is available on the user's MIDI instrument
   (eg those with GM support).

3.3 SWI Interface
-----------------
   The SWI interface includes equivalent commands to the CLI :
      * Ethereal_Play
           On entry : R0 = pointer to MIDI file in memory
                      R1 = -1 - one-shot play
                            n - looping play with n ms loop delay
      * Ethereal_Stop
           No parameters required

   Important: Immediately after loading a file, make a call to
   Ethereal_Verify to check its format and act on the diagnostic
   number returned :
      * 0  - OK
      * 1  - not a MIDI file
      * >1 - corrupt MIDI file
      
   Full details of *all* SWIs are given in the EtherealMidi Reference Manual.  


4. Terms and Conditions
=======================

   This package is supplied as FreeWare for non-commercial use.
   Please check the 'Licence' file included with this suite for
   full details.

   In layman's terms, no charge should be made for the software
   itself. It's free. A suitably small charge *may* be made for the
   media on which it is supplied and its distribution.

   The source code has not been supplied and is not Public Domain.
   This allows sensible version control. If you find a bug, let me
   know and I'll fix it (see 'Troubleshooting').


5. Troubleshooting
==================

   This section is designed to help rectify 'easy' problems. If you
   encounter one not on the list, please check the 'Known Bugs'
   section, below, and the 'Limitations' section of the
   EtherealMidi Reference Manual.

   If you are still unsuccessful, please contact the Author with as
   much detail as possible about the circumstances under which the
   problem occurs (see 'Contact Address'). 

Problem            Possible solution
-------            -----------------
'*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
file'              * EtherealMidi module crashed - '*RMReInit EtherealMidi'
& no playback      * MIDI leads incorrectly connected - connect Arc's MIDI OUT
                     (port 0) to instrument's MIDI IN
                   * MIDI instrument in odd state - switch instrument off and
                     then on again or use Monolith's 'Reset' option
                   * MIDI instrument not receiving on relevant MIDI channel -
                     find out about MIDI channels  & use '*EtherealMap'
                   * MIDI leads damaged - new leads
                   
'*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
file' only plays   * EtherealMidi module crashed - '*RMReInit EtherealMidi'
a few notes        

'*EtherealPlay     * MIDI module crashed - '*RMReInit MIDI'
file' causes a     * EtherealMidi module crashed - '*RMReInit EtherealMidi'
beep               

Double-click file  * Alias not set up - double-click !Monolith again or drag
& no playback        file directly to Monolith icon/window
                   * Incorrect file type - '*SetType filename FD4'
                   * Try '*EtherealPlay filename'

Notes left on      * Used '*EtherealMap' during playback - '*EtherealPlay'
                   * Crash/reset - '*EtherealPlay'
                   * MIDI instrument in odd state - switch instrument off and
                     then on again or use Monolith's 'Reset' option

Playback, but not  * Must *start* play with looping option selected - try 
looping              '*EtherealLoop filename'
                   * From Monolith, dynamic looping control is permitted, but
                     not in Game mode - check Game mode is off

Playback stops or  * Second program is :
hangs when another      a. preventing interrupts
program is run          b. using Timer 1 (User Timer)
                        c. using MIDI interface
                     - use '*EtherealPlay' to stop playback before running
                       second program
                     

6. Known Bugs
=============

   A simple troubleshooting guide is outlined in the
   'Troubleshooting' section. If you think you have found a bug,
   please check this section and the 'Limitations' section of the
   Reference Manual before contacting the Author. Sensible
   suggestions are also welcomed.

   The module should fail safe if a problem occurs. There is a
   possibility of the MIDI module crashing. EtherealMidi may *not*
   report a formal error if this happens, but will beep, and should
   always stop safely.

6.1 Acorn Compatible ?
----------------------
   If you are using a MIDI interface from 'Serial Port' (later
   'Leading Edge', 'Vertical Twist', 'VTi', 'QD Enterprises'),
   EtherealMidi may not work with your system. I bought the version
   of this MIDI interface which fitted in the EcoNet slot when it
   first came out (about August 1990, I think). The MIDI module
   support software simply didn't do what it claimed to be capable
   of. I informed them of this fact on numerous occasions in the
   following years, and even disassembled their entire MIDI module
   to locate the problem(s).

   At Acorn World 94, I was told they had licensed Acorn's code so
   it would now work perfectly and I would be sent a copy. At Acorn
   World 95, having not received the new software, I demanded (and
   finally got) my money back. I was then told they no longer
   supported MIDI. I now have a Morley MIDI interface and it works
   a treat.

6.2 System Exclusive
--------------------
   The Acorn MIDI User Guide (AMUG) is extremely unclear about the
   use of the scheduler to transmit System Exclusives. Careful
   examination of AMUG shows it should be possible to achieve this,
   but in reality it may not be.

   To test your own Acorn MIDI system, use the SXTest program (in
   the Test subdirectory) and follow its instructions. If your
   system passes the test, I would really like to hear from you. I
   distributed a version of SXTest after some discussion in the
   comp.sys.acorn.* newsgroups. Despite receiving several sets of
   results, not one of them was a pass. If your system fails, I
   would still like to hear from you as it might encourage me to
   fix it.

   The test software has now been improved to make it easier to use
   and more comprehensive. More details of the test are included in
   the SXTestDoc file in the Docs subdirectory.

   
7. Acknowledgements
===================

   * Mum and Dad for recognising that computers weren't just a 'passing phase.'

   * Mr Gibson (my late piano teacher) for teaching me to play.

   * Acorn Computers for their superb machines.
   
   * Morley Electronics for all their help with purchasing a MIDI interface.
     (see 'Known Bugs - Acorn Compatible ?')
   
   * R A Penfold for his excellent introductory book to MIDI.

   * Michael S. Czeiszperger for his explanation of standard MIDI files.
   
   * Steven Singer for his continuing interest and helpful suggestions.

   * Simon Hatliff for having the good sense to want to include MIDI in his
     multi-format music player, PDTracker.

   * James Hammerton for spotting a timing bug that's been there since the
     first release. Doh!


8. Contact Address
==================

   To contact the author, write to :

   R J K Smith
   12 Cornelia Close
   Southwood
   Farnborough
   Hampshire
   GU14 0PE

   Please include an email address if you have one.

   Or simply email rjksmith@arcade.demon.co.uk

   
 Copyright Rob Smith 1996,1997 (Last updated: 28/09/97)

EtherealMidi Licence
====================

   This file details the legal aspects of the EtherealMidi software
   suite. A more user-friendly guide is included in the 'Terms and
   Conditions' section of the EtherealMidi User Guide.

*  The EtherealMidi software suite (hereafter referred to as
   'EtherealMidi') is comprised of those files listed in the
   unmodified 'FileList' catalogue file.

*  EtherealMidi may be freely distributed for non-commercial
   purposes. No charge may be made for EtherealMidi itself. A small
   charge may be levied to cover the cost of the media on which it is
   supplied and for the distribution of that media.

*  Mr R J K Smith (hereafter referred to as 'the Author') retains
   copyright of EtherealMidi at all times.

*  All distributed copies of EtherealMidi must include this
   'Licence' file, an unmodified copies of the 'FileList' catalogue
   file and all the files named in the 'FileList' file.

*  Files named in the EtherealMidi 'FileList' catalogue file may
   not be modified without the prior written permission of the Author.

*  EtherealMidi may NOT be distributed with commercial (including
   magazine) software without the prior written permission of the
   Author. If profit is being made from the accompanying software,
   then permission will normally be granted in exchange for a small
   remuneration. The contact address of the Author is given in
   EtherealMidi User Guide.